/*
 * File     : Allocator.java
 * Created  : 1 May 2011
 *
 * Copyright © 2011 Matthew Wilson (mj. {my-surname} .uk {at} gmail.com)
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package com.googlecode.dni;

import java.nio.ByteBuffer;

import com.googlecode.dni.type.Pointer;


/**
 * <p>
 *  Encapsulates a service that allocates memory.
 * </p>
 * <p>
 *  By default, DNI uses its own service that is used by Java's direct
 *  {@link ByteBuffer}s (but not adjusting the amount of "direct byte buffer
 *  heap"&mdash;not a real heap&mdash; taken).  The service can be replaced as
 *  required by setting {@link InitialisationOption#ALLOCATOR}.
 * </p>
 *
 * @author Matthew Wilson
 */
public interface Allocator
{

    /**
     * <p>
     *  Allocates <code>size</code> bytes of memory, setting them all to zero.
     *  The memory will be aligned suitably for any machine-specific type to be
     *  used correctly.
     * </p>
     *
     * @param size
     *            the number of bytes; zero size is not permitted
     *
     * @return a pointer to the first allocated byte
     */
    Pointer allocate( int size );

    /**
     * <p>
     *  Allocates <code>size</code> bytes of memory, copying in the values from
     *  the given memory location.  The memory will be aligned suitably for any
     *  machine-specific type to be used correctly.
     * </p>
     *
     * @param sourcePointer
     *            the source pointer
     * @param size
     *            the number of bytes; zero size is not permitted
     *
     * @return a pointer to the first allocated byte
     */
    Pointer copy( Pointer sourcePointer, int size );

    /**
     * <p>
     *  Frees memory allocated via {@link #allocate(int)} or
     *  {@link #copy(Pointer, int)}.
     * </p>
     * <p>
     *  Takes no action if the pointer is {@link Pointer#NULL}.
     * </p>
     *
     * @param pointer
     *            the pointer
     */
    void free( Pointer pointer );

}
